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Supporting Document 
Development with Concordia 


4 6 D ocumentation projects are 
always behind schedule 
and over budget, and the 

quality of the final result is disappoint- 
ing.”’ ‘‘Documentation is a problem that 
everybody knows about and wishes would 
just go away.’’ ‘‘Nobody ever really wants 
to write technical documentation; it’s the 
boring afterthought after all the hard work 
is finished.’’ 

What causes this kind of popular per- 
ception about technical documentation? 
Why is documentation the unglamorous 
part of most projects? Could it be due to 
a lack of appropriate technology for sup- 
porting the job? While software 
developers have long produced software 
development environments for them- 
selves, few people have addressed the 
analogous working environment issues for 
technical writers.! 

It is surprising that software develop- 
ment environments and document devel- 
opment environments have remained quite 
separate, since writing code and 
documenting it are really the same kind of 
effort at some abstract level. Document 
engineering is no less an intellectual chal- 
lenge than software engineering, and cer- 
tainly offers a greater operational 


Another version of this article appears in Conference 
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Concordia applies 
object-oriented 
techniques to creating, 
publishing, and 
maintaining complex 
documentation. Using 
this highly integrated 
working environment, 
writers move beyond 
conventional limits on 
their productivity. 


challenge in the absence of appropriate 
technology. 

To address these issues, we designed and 
implemented a development environment 
for technical writers. This environment, 
which we call Concordia, is an extension 
of Genera, the software development envi- 
ronment provided on Symbolics com- 
puters.? We built it for the same 
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development paradigm, using the same 
substrate as the Genera system, and it inte- 
grates seamlessly into Genera as a concep- 
tual extension. 

Concordia integrates the facilities 
needed to create, revise, publish, distrib- 
ute, and maintain very large document sets 
with very long life cycles. It provides an 
environment for professional communica- 
tors to create and maintain large informa- 
tion bases of text and graphic information, 
with the capability for large-scale informa- 
tion development and delivery. Various 
generations of this application have been 
used in-house at Symbolics since 1984 for 
producing system software documen- 
tation. 


Authoring environment. In their daily 
work writers create, revise, publish, and 
maintain a document database. Concordia 
has specialized support for the different 
phases of a document life cycle: writing, 
editing, illustration, design, production, 
and maintenance. 

For small jobs, a single person could 
take on all roles in the process; personal or 
desktop publishing systems support this 
model of document production. (For the 
advantages and disadvantages of desktop 
publishing in handling documentation, see 
the sidebar ‘‘What about desktop publish- 
ing?’’) For large documentation jobs, 
tasks are typically performed by different 
people at different times or by the same 
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person at different times. Accordingly, 
Concordia supports the different tasks 
with their own software facilities. For 
example, the environment separates 
specifying book design from editing con- 
tent. Likewise, it separates production 
from modification of the document’s 
overall structure. 

Despite separate support for each task, 
a single application integrates all of the 
environment’s capabilities. As writers’ 
tasks change at different times in the docu- 
ment’s life cycle, they use different abili- 
ties of the application. Thanks to the 
integration, parts of a developing docu- 
ment are always available when needed, in 
the format required. Concordia requires 
no format conversions to move from one 
kind of task to another. 


Goals and design 


The Concordia development project 
had the following broad goals: enhance 
productivity of technical writers, speed 
time-to-market for documents, streamline 
document maintenance processes, reduce 
maintenance costs, and increase flexibility 
in document delivery options (including 
on-line delivery). 

Our somewhat abstract productivity 
goals became more concrete implementa- 
tion projects: a database for documents,* 
embodying hypertext’ concepts; a struc- 
ture editor, combining concepts from 
what-you-see-is-what-you-get editing 
(called WYSIWYG) and generic markup 
languages®; an object-oriented graphic 
editor for manipulating illustrations; con- 
figuration tools for managing versions and 
postproduction distribution; incremental 
development tools to support a group of 
writers cooperating on the development of 
a large document set; and a flexible inter- 
face for on-line inspection of documents 
during development and for final delivery 
to customers. 


Architecture. Concordia is part of the 
Symbolics documentation system, 
diagrammed in Figure |. The central com- 
ponent is the documentation itself, 
arranged in a database of independently 
accessible records maintained using Con- 
cordia. End users can retrieve information 
from the database using Document 
Examiner,’ the delivery interface for on- 
line lookup. We also deliver the database 
as published manuals, in conventional 
paper form, and could extend to other 
electronic media. 
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Figure 1. Document system architecture. The central component is the documenta- 
tion itself, arranged in a database of independent records. This database is written 
using Concordia. End-user retrieval from the database is handled using Document 
Examiner, the delivery interface for on-line lookup. The database can be published 
as conventional paper manuals or in various electronic forms. 


What about desktop publishing? 


Doesn't desktop publishing provide the key to solving all documentation 
problems? Desktop publishing has done much to speed up document produc- 
tion, with many of the same goals as Concordia—more productive documen- 
tation departments producing more cost-effective publications faster. 
Effective as it is for the right jobs, desktop publishing is designed for a differ- 
ent kind of document than Concordia. 

The differences between desktop publishing and Concordia become appar- 
ent only when you examine the documents, their life cycles, and the 
processes used to produce them. Desktop publishing is designed for short 
documents (from five to a practical limit of around 50 pages) produced for a 
single use, often by one person. Concordia was designed for large documents 
(hundreds or thousands of pages) with very long development and life cycles, 
maintained by a team of writers. 

In a short document, relatively little time goes into preparing the content of 
the document; most of the effort goes into typesetting, layout, and final 
production. Desktop publishing moved control over those details into the 
hands of the people creating the document, thus reducing delays and mis- 
communication and giving people more control over their own products. 

In large documentation projects, the development (writing) stages take over 
half of the project resources, while final production takes much less (less 
than 10 percent according to some estimates). Therefore, to improve produc- 
tivity and reduce costs in large documentation projects, you need to concen- 
trate on the development cycle; relatively small gains come from improving 
the final production cycle. 

Desktop publishing systems differ in the details of their features, but all 
have essentially the same goal—good layout of text and graphics on paper 
for subsequent reproduction. Many desktop publishing systems have only a 
primitive word processor, on the assumption that the actual preparation of 
the text happens elsewhere. They provide primarily a publishing facility, with- 
out features for assisting large-scale development. 

Concordia, on the other hand, changes the nature of document develop- 
ment instead of simply speeding up the manual production process. 
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Figure 2. Document structure. Independent records in the database are represented 
by the ovals labeled A through G. Records can refer to each other by way of links, 
which have types. The links labeled i are inclusion links, specifying that the target 
record is included at that point; the links labeled r are conventional cross-reference 
links. The figure shows what a reader of records A and G would see. The i links 
have been replaced by the contents of the target records and the r links have been 


replaced by cross-reference sentences. 


Document database. Conceptually, the 
documentation is organized as a database 
of interconnected modules called records. 
A record is a unit of information retriev- 
able from the database, as well as a seman- 
tic unit of the subject matter. Think of 
records as semantic cut-and-paste units. 

Records contain the subject matter from 
which we construct documents. A docu- 
ment is formed by linking records 
together, much as a program is formed by 
the calling structure of subroutines and 
functions. Figure 2 diagrams the creation 
of a document from a set of records by 
means of links between the records. We 
use this mechanism for creating conven- 
tional hierarchical documents from a col- 
lection of independent units. The records 
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are reusable units and can be used in more 
than one document. 

Writers decompose subject matter into 
records fairly naturally in most cases, since 
the divisions depend on the conceptual 
structure of the subject matter. Reference 
material and definitions of terminology 
easily separate into independent records. 
Conceptual and tutorial materials are 
harder to organize, much the same as in 
conventionally written manuals. Asarule 
of thumb, writers construct a separate rec- 
ord for any item of information that a 
reader might need to access directly. Thus 
the process of constructing the records for 
a document relates to the purpose of the 
document and the needs of the audience. 
As with software modularity, it takes expe- 


rience and judgment to construct well 
modularized documents. 

This conceptual database is not cur- 
rently implemented using any standard 
database technology. Instead, we based 
our implementation on a set of binary files 
containing records and indexes. The data- 
base consists of any number of document 
sets (one set for each software product), 
where each document set contains one or 
several books. (A good explanation of the 
concepts of document databases appears 
in James.*) Abstractly, we have books 
within document sets within the database; 
physically, we have records within files 
within a collection of configuration- 
controlled systems. 


End-user delivery interface. We deliver 
documentation to customers both on 
paper and on line. On-line delivery is more 
important because it represents the future 
direction for information delivery in the 
computer industry. 

On-line delivery of the document data- 
base is managed by Document Examiner, 
a window-based utility closely integrated 
with the rest of the Symbolics software 
environment. (See the sidebar ‘‘An on-line 
manual’’ for further information on 
Document Examiner.) In the course of 
developing documentation, writers often 
use the facilities of Document Examiner to 
see how a particular section will appear to 
its readers. 


Creating and editing 
documents with 
Concordia 


Concordia is a framework organizing 
the tasks and activities in the document life 
cycle. The three major subactivities are 
text editing, graphic editing, and 
previewing. 

Its editor is the major software compo- 
nent of Concordia, since the majority of 
time in a complex project is spent in devel- 
opment, not in proofing, layout, and 
production. Concordia modifies and 
extends the standard software editing par- 
adigm of Symbolics Genera to suit large- 
scale document editing jobs. Figure 3 
shows a screen display of Concordia, with 
the editor visible. The editor is a structure 
editor, capable of manipulating the 
records represented within files.® 

The text editing component of Concor- 
dia, called ConEd, provides editing capa- 
bilities that are not WYSIWYG yet do not 
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Concordia 


When you enter Converse for the firet time, the window le 
empty except for a blank message at the top of the 
screen, starting with To:. 


You start a message by filling In a recipient after the 
To:, pressing RETURN and then typing the message text. 
It Is not necessary to know what machine the person Is 
using, but If you do know and give the recipient as 
name@host the massage is sent considerably faster since 
it Is not necessary to search the namespace to find the 
machine. To send the finished message, press END. 


Figure 


To: KJones@Wonbat 
Do you have a ninute now? 


& Caption: <A Converse Message About to be Sent> 
(Figure 
When the message has been sent successfully, It appears 


as part of a conversation. A blank message remains at 
the top of the screen, and just below that, a heavy black 
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line delimits the message(s) of the conversation you just 
started. Just below the heavy black line je another blank 
message, but this one has the name of the person to 
whom you sent the message filled in. Below this blank 
message, separated by a thin black line, the message 
you Just sent appears, with the date and time It was 


sent. 


nacs 2 (WriterTools 


Hore above and below. 


Beginning 
End 


Create 

Make Language form 

Remove Markup 

ne Environment 
i 

Show Definition 


Figure 3. Concordia screen display, showing the ConEd document editor. It shows part of a record in which a figure appears. 
The right-hand panel is a command menu showing the commands that manipulate record structure and appearance. All of 


these commands can be issued via keyboard commands as well as by using the menu. 


require writers to maintain document 
sources in a conventional textual markup 
language. ConEd implements an amalgam 
of these capabilities that we call semblance 
editing. 

WYSIWYG editing requires writers to 
attend simultaneously to structure, con- 
tent, and appearance. For small jobs, 
writers can fail to notice the conceptual 
differences between these aspects of a 
document. The emphasis in WYSIWYG 
editors (in fact, their raison d’étre) is on 
controlling the appearance of a document. 
This partially carries over from the days of 
typing pools, when the typist’s only job 
was to ensure the good appearance of the 
text. Writers of large document sets should 
care little about final appearance during 
development. What they do care about 
during development is being able to 
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categorize the information for display— 
text, headings, tables, lists of various 
kinds, and so on. 

Concordia uses a generic markup lan- 
guage for documentation because of the 
importance for writer productivity of 
separating content from form. The differ- 
ence between this and other edi- 
tor/formatter systems based on generic 
markup is that users do not edit text inter- 
mingled with textual commands. (For 
more on formatting, see the sidebar ‘‘For- 
matter command languages.’’) Instead 
they edit a semblance of the final result, as 
shown in Figure 4. 

The figure contains an example of 
markup, indicated by the small boxed 
delimiters surrounding a text area on the 
screen. Itemize is a specification about the 
communications intent of the enclosed text 


(and, eventually, its appearance). The list 
is indented and set off from the body text 
much as it would be ina WYSIWYG edi- 
tor. Unlike WYSIWYG, there is no 
attempt to show the nature of the high- 
lighting or the exact details of the sur- 
rounding spacing. What you can’t see 
from looking at the figure is that the writer 
typed in only the request for markup, not 
any of the formatting effects; ConEd 
made the decisions about spacing and 
indenting. 

Rather than doing real-time formatting, 
ConEd shows the writer some semblance 
of the final formatted result. This provides 
the feel of a WYSIWYG editor without 
sacrificing any of the power of a generic 
markup language. ConEd supplies for- 
matting on demand of any region of the 
text, for occasions when the semblance is 
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not sufficient for the writers’ needs. (3) format—the appearance of the each of these four kinds of information. 


In creating documents, writers must document (in a typographic and They should be able to consider each 
manage four different kinds of infor- information design sense); and aspect of a document relatively indepen- 
mation: (4) meta-information—auxiliary dently of the others, and not have to work 

(1) structure—the organization of information not generally part of simultaneously at several levels of dis- 

material, for example, in a chap- what the reader of the document course. 
ter/section/subsection hierarchy; sees, but relevant nonetheless to 

(2) content—the subject matter of the its development. Structure editing. In Concordia, records 

document; Writers need assistance with managing are the raw material from which docu- 


An on-line manuel 


How important is on-line dativers for documentation? Would good user interface. 


anyone read manuals on line tf they could have paper instead? The interface to our on-line manual, called Document 

With over four yeans experience belt lind us, we believe that on- Examiner, is an independent window-based utility closely inte- 
line manuats are highly, fe q use Our manuals heavily grated with the rest of the Symbolics Genera environment. 

on line, with some softwareenginears reporting that they use The window is divided tnto panes (subwindows) that help 

the on-line version. és vély. The:on-line manual has exactly users manage various aspects of their Interaction with the 

the same contents as: the pr yted manuals detivered with the document. (See the accompanying figure on Document 
system, because both aie prodkiced from the same database Examiner's screen-display.) 

of records. So people choosa.the. on-line manual based on The majority of the screen area is used to show a topic. It 
satisfaction with it, not of in content. The key ele- gives people the feeling of-reading a section from a book. The 
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Flie-System errors 


The following condition flavors are part of the Symbolics Lisp 
Machine’s generic flie system interface. These flavors work for all file 
systems, whether local Lisp Machine file systems, remote Lisp 
Machine fille systems (accessed over a network), or remote file 
systems of other kinds, such as UNIX or TOPS-20. All of them report 
errors uniformly. 

Some of these condition flavors describe situations that can occur 
during any file system operation. These include not only the most 
basic flavors, such as fs:fle-request-fallure and fs:data-error, 
but also flavors such as fs:ftle-not-found and 
fs:directory-not-found. Other file system condition flavors 
describe failures related to specific file system operations, such as 
fe:rename-failure, and fs:delete-failure. Given all these 
cholces, you have to determine what condition ls appropriate to 
handle, for example In checking for success of a rename operation. 
Would fs:rename-fallure inciude cases where, say, the directory of 
the file being renamed |s not found? 

The answer to this question is that you should handie 
fs:flle-operation-fallure. fe:rename-failure and all other 
conditions at that level are signalled only for errors that relate 
specifically to the semantics of the operation involved. if you cannot 
delete a file because the file Is not found, fs:file-not-found would 
be signalled. Suppose you cannot delete the file because Its ‘don’t 
delete switch® is set, which is an error relating specifically to 
deletion. fa:delete-failure would be signalled. Therefore, since you 
cannot know whether a condition flavor related to an operation 
requested or some more general error Is signalled, you usually want 
to handle one of the most general flavors of file system error. 

Under normal conditions, you would bind only for 
fs:flle-request-faliure or fs:file-operation-failure rather than 
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Document Examiner screen display. The viewer area contains the first screentul of a section, whose bookmark is marked in the 
bookmarks pane. The cantiidatés pane contains the results of a search for relevant topics. Several recent commands are visible 
in the command'pane. 
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ments are constructed. Structure is 
imposed on the raw material by links from 
one record to another (as sketched in Fig- 
ure 2). The links are all executable; they tell 
the formatter or displayer to include the 
target record as if it were part of the origi- 
nating record. Figure 4 shows a record 
containing literal text as well as a number 
of links to other records. 


The position of a record within a docu- 
ment depends on the links to it. If the top- 
level record is called a chapter, then the 
records it has links to would be called sec- 
tions; the records that those sections link 
to would be called subsections, and so on. 
These organizational levels are not part of 
the records themselves, but rather are 
assigned dynamically by the process of 


viewing the record—from a reader’s point 
of view. 

In one sense, a document is a directed 
graph structure. Editing this structure 
requires a specialized set of commands for 
manipulating both records themselves and 
the links among them. 


Creating a record, Since records are 


menu and a command interactor area where the user can type 
commands. (Most commands can be invoked with either the 
mouse or the keyboard.) 

To find relevant sections, users have commands that let 
them do the on-line equivalent of tooking in the index and 
table of contents for the document set. The set of interesting 
sections (called candidates) is listed in a menu at the top right 
of the screen. Candidates are mouse-sensitive, so a user can 
click directly on a name to read it or look at how it fits into the 
document set. 

Anyone using a document needs bookmarks to keep track 
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[Section “Using Zmail™ 
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Using Zmall, you can send and receive electronic mall, 


archive your mail In disk files, and operate on groups of OM Links From Record 


messages selected according to very flexible criteria. 


This tutorial provides a brief Introduction to the basic 
features of Zmail. For a complete description of all 


2mall’s capabitities: 


4 See the section Zmail Reference Guide. 


This section covers the following topics: 


[itemise 


Starting up the Zmall mall reader. 


Sending a message to another user. 


Reading mall that other people send to you. 
itemize 


3 Include link to "Starting up Zmall! (sectlon)" 
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Zmall is a display-oriented mall system for managing electronic mall. 


[netines. 

[Reywords 
Electronic mail 

. 


aywere 
[End of *Using Zmall® record 


Hore above and below 


Show Links To Record 
Graph Links From Record 
Collect Record Name 
Create Link 


Records 
Beginning 
End 


Add Record Field 
Rename 

Show Status 

Verify 

Add to Database 
Remove from Database 
Show Recorde in Buffer 
Reorder Records 


Beginning 
End 


Create 

Make Language form 

Remove Markup 

cranes Environment 
+ 


Kilt 
Show Definition 


Figure 4. ConEd screen, showing a complete record containing appearance markup and links to other records. Small boxed 

delimiters (Itemize) show the extent of formatting markup. The vertical spacing and shifted left margin constitute a semblance 
of the final formatting effects. When this record is processed from a reader’s point of view, the records that are the targets of 
the links are included dynamically as sections within this record. 


structural rather than textual elements, 
writers can’t just ‘‘type in’’ new records. 
Instead, commands are provided for creat- 
ing records, with a template supplying 
standard fields and sometimes initial con- 
tents for the fields. For example, in creat- 
ing a new record for a function, Concordia 
fills the argument list field from informa- 
tion in the compiled object database. A 
number of validation checks run during 
record creation ensure against uninten- 
tional duplication and spelling errors in 
definition names. 


Creating links. Again, since the links 
between records are structural rather than 
textual, ConEd provides commands for 
creating and changing them. To create a 
link from one record to another, you place 
the cursor at the desired origin of the new 
link, click on the Create Link command, 
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and then supply the target record. You can 
type in the target name, but more often 
would click on it, either on the main screen 
or in the pane of collected record names in 
the bottom right corner (Figure 4). 


Changing the organization. You change 
the organization of a document (for exam- 
ple, the order of subsections within a sec- 
tion) by changing the order of the links. 
You can move a whole subtree of the docu- 
ment simply by moving the link to the root 
of the subtree. Asa result, you can quickly 
evaluate a number of different organiza- 
tions for material with little risk of becom- 
ing confused or inadvertently deleting 
material without pasting it back. 


Showing relationships between records. 
ConEd supplies several commands to help 


you visualize the structural relationships 
between records. A table of contents 
shows the complete subtree below any rec- 
ord to help in visualizing the structure. 
Other commands show all of the links 
from the current record or all of the links 
that point to it. Being able to see the links 
to a record allows you to manage cross- 
references to it. 


Selecting a record for editing. Although 
you can scroll around in ConEd buffers or 
select buffers by name (as in normal text 
editing), you can also select records 
directly, by name, for editing. ConEd uses 
a location database (maintained by the 
Concordia compiler) to select a record. It 
ensures that the relevant file is in a buffer 
(reading it in if necessary), selects the 
buffer, and positions the cursor so that the 
requested record is visible on the screen. 
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Figure 5. Graphics editor. The main body of the editor contains a figure being edited. The right-hand panel contains several 
kinds of menus, including a command menu, a shape menu, and a control panel for attributes of the editing. Most of the edit- 
ing can be performed by typing in commands as well as by mouse selection. 


This removes any need to remember file 
names or perform textual searches to 
locate material to be edited. Instead, you 
remember record names—an easier task 
aided by substantial on-line help. Record 
name presentations on the screen are 
mouse-sensitive, so you can click on the 
name of a record to select it for editing. 
This makes sequential editing from a 
marked-up manuscript simple in spite of 
the underlying modular structure. 


Content editing. Documents usually 
consist of text and pictures. (With com- 
puter delivery, other media for documen- 
tation such as video, sound, and animation 
will become feasible as well.) In Concor- 
dia, ConEd handles the textual subject 
matter; an editor for line illustrations han- 
dles the graphic subject matter. Using its 
knowledge about record types, Concordia 
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switches automatically to the editor appro- 
priate for the subject matter. 

The ConEd editor is the top-level frame- 
work for handling all aspects of document 
editing; the graphic editor simply prepares 
graphical subject matter for incorporation 
into the records managed by the text 
editor. 

The parts of a record that look like text 
are text; you use standard text editing com- 
mands (as opposed to structure editing 
commands) to modify them. ConEd has 
sufficient understanding of the compo- 
nents of text to manipulate words, sen- 
tences, and paragraphs (the units of text) 
as well as characters and lines. (ConEd is 
an extension of Genera’s Zmacs editor, 
which also has these text handling capa- 
bilities.) 

The parts of a record that look like pic- 
tures are pictures. Concordia’s own 


graphics editor is an object-oriented edi- 
tor for line illustrations. It stores drawings 
as structured descriptions rather than as bit 
maps to enable flexible editing of structure 
instead of pixels. To modify one of these 
pictures, you click on it with the Edit com- 
mand and Concordia automatically 
invokes the graphics editor (see Figure 5). 
Pictures can also be accommodated in a 
number of other formats, including Lisp 
graphics programs, bit maps, Postscript, 
and externally generated pictures (like 
those from MacDraw), 


Appearance editing. In Concordia, a 
markup language controls the appearance 
of documents. Unlike most other markup 
languages, the markup is not embedded 
text strings. 

Markup is the term used for non- 
procedural descriptions of the generic cat- 
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Concordia 


Environment Name: Itenize 
Above: @.5 Lines 


Below: @.5 Lines 

Indent: ~2 Characters 

Leftmergin: +2 Characters 

Spread: 8.5 Lines 

Other Attribute: an attribute nane 


ERD aborts, QD uses these values 


[itemtaa 


to be specified manually. 


Blanktines: Break Hinge Hingebreak Hingekeep 


Tgnore Ignored Kept 


Click on this line to reset attributes to default values. 


Writers don’t have to remember details of standards 
for the appearance of various effects, only the kind 
of effect they want and Its name. 


Editing is faster because the name specifies many 
parameters, like changes In margins, spacing, style, 
and placement of bullets, that otherwise would have 


Writers don’t have to waste time on formatting 
In the early stages of development. 


Subsequent maintainers can see what the original 
author meant, not just what the document looked like. 


Generic formatting specifications are device- 
Independent, giving more flexibility and higher quality for 


a range of output devices. 


Corporate formatting standarde can be established 
and revised whenever necessary without affecting 
books under development or books already 


completed. 


Ttemize 


Zmacs 2 (kriterTools Fill 
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die Environment Attributes WH<SAGE : :SAGE-TEXT-STRUCTURE 141917763) 
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Figure 6. Local markup modification in ConEd. The writer has selected the Itemize markup for modification, bringing up a 
menu of the attributes involved in its standard definition. After changing and saving the attributes, the changes apply to this 
one instance, leaving the standard definition unchanged. 


egory of information in some region of 
text. (Figure 4 contains examples of 
markup.) The markup is delimited visually 
by small iconic boxes. These delimiters are 
structural rather than textual, meaning 
that text editing operations do not apply 
to them. For example, the text command 
to delete a line does not delete a delimiter 
line. 

All markup is manipulated by special- 
ized commands, some of which appear in 
the right-hand menu in the ConEd figures. 
Commands are used to add markup to 
existing areas of text and to remove either 
just the markup or the markup and the 
relevant area of text. As a result, all of the 
markup in a record is syntactically correct; 
no formatting errors can occur later as a 
result of missing or extra delimiters (com- 
mon errors with text-based embedded 
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markup formatters). 

ConEd itself shows a semblance of what 
the final document product will look like. 
Bold, italic, and fixed-width typefaces 
appear as such in the editor window, rather 
than being indicated by font change 
characters or embedded notation specify- 
ing the typeface. The final format, how- 
ever, is only suggested by indentation, 
which serves as an aid for checking visually 
that the markup includes only the intended 
text. 

The markup that controls formatting is 
backed up by a book design, which defines 
the appearance parameters for all markup 
used in a book. Markup definitions can be 
changed globally (in Concordia’s book 
design environment) or locally in ConEd 
for a particular case. Figure 6 shows the 
mechanism by which you would use 


ConEd to change the appearance specified 
for a particular instance of a highlighted 
list. Clicking on one of the markup 
delimiters brings up a menu of formatting 
attributes to modify. The modifications 
are then saved as part of that markup 
object. 


Handling meta-information. WYSI- 
WYG editors require by definition that the 
document file contain only the informa- 
tion that will appear to the final reader of 
the document. They require the rest of the 
information associated with a document to 
be maintained on paper, informally in 
unrelated files, or in people’s heads. 
Embedded command formatters usually 
allow comments as an unstructured way of 
capturing some of this information. The 
record structure in Concordia provides 
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Page Previewer command: Next Page 
Page Previewer command: Next Page 


Seu 
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roan bach 
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Page Previewer command: Set Page (page number [default 6]) 2 


Page Previewer command: 
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Figure 7. Hardcopy preview. A page previewer shows an exact facsimile of the placement of lines and page breaks. Spacing 
and fonts used in the preview are different from those on the final output device due to differences in resolution. The place- 
ment of words in lines, however, is exactly the same, so this previewer can be used for surveying the progress of the layout. 
(Note: The text is not intended to be legible because this is used for design purposes, not proofreading.) 


fields for storing accessory information 
(for example, keywords, auditing infor- 
mation, and notes) and, in some cases, for 
processing it. 

One kind of meta-information stored in 
arecord is its verification status. Concor- 
dia keeps track of whether records have 
been formatted since being changed or 
changed without being installed in the 
database. This status information is used 
by various commands to help writers keep 
track of their workload. 


Viewing and reviewing 
documents 


At different points in the document life 
cycle, writers need different ways of look- 
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ing at their work. Concordia provides a 
number of ways to view a document. 


Seeing the reader’s viewpoint. The sem- 
blance editing in ConEd gives a good indi- 
cation of the formatting structure within 
arecord. It is often necessary, however, to 
look at a record from the perspective of a 
reader, with its links expanded. ConEd has 
a facility for formatting on demand that 
shows arecord formatted on the screen as 
the eventual reader of it would see it in 
Document Examiner or on paper. 


Local hardcopy. You can produce hard- 
copy of any topic (a record and its expan- 
sions) in the database. Whether or not to 
use paper is a question of personal prefer- 
ence, since paper is not required for any 
stage of development. 


Preview. During final production of a 
paper manual, you must consider the 
placement of ink on paper. For this stage, 
Concordia provides a page formatter that 
shows on the screen a miniature but exact 
facsimile of how the document will appear 
when printed (see Figure 7). You can iden- 
tify badly placed page breaks and poor 
formatting decisions (and then fix the 
source files) without having to print out 
any paper copy at all. The text in this 
previewer is not supposed to be legible; it 
is used for proofing the overall layout, not 
the text. 


Final hardcopy. As the last stage in 
production, Concordia produces print 
masters for each book, expressed in Post- 
script.” The masters contain everything 
needed to print a book (front matter, table 
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of contents, index, figures, running 
heads), leaving very little manual! work in 
final production. 


Production 


requires effective configuration manage- 
ment tools, since manually managing the 
files involved in various versions of a large 
document set is very difficult. Concordia 
uses the system configuration tools (SCT) 
in Genera to address these information 


for specifying a document set as asystem. 
A system is a formal data structure that 
manages a set of files and defines the oper- 
ations available for those files, such as 
editing, formatting, updating, and dis- 
tributing. 


management requirements. 


Managing the files for a large document 
set consisting of one or more books 


Formatter command languages 


Before WYSIWYG editing and desktop publishing, people 
lucky enough to have access to time-sharing computer sys- 
tems used embedded-command batch formatters for their 
documents. The documents wefe plain text files with format- 
ter commands intermingled with the text; a flag character indi- 
cated the presence of a command. 

The following shows examples of three major famities of 
such formatters, the dot-in-column-one formatters (like Run- 
off), the \ formatters (like TEX’), and the @ formatters (like 


* If call-next-method is used in an :around method ... 


\beginlist 

\item{\buil} 

If {\bf call-next-method} is used in an {\bf :around} 
method... 


@beginfitemize} : - 
lf @bicall-next-method] is ikea in an @bf:around] method... 


Many of these formatters had advanced macro and pro- 
gramming capabilities and are still in use today because they 
have a number of advantages over the WYSIWYG approaches. 

There are two basic classes of command languages for 
specifying document formatting— procedural languages and 
declarative languages. The procedural languages (like Runoff), 
require writers to specify all formatting directly, in effect “pro- 


gramming” their documents. Some allow macros as away of 


masking the programimitg arid simplifying the document 
sources. The declarative languages, of which Scribes the 
best exaniple; spectty wivat the text is in.an abstract sense 
and leave the exact specifications about appearance toa 
book design database... 

Declarative languages: introduce a level of abstraction that, 


separates the kind of formatting. wanted from the exact details - | 


of how to produce it. Thus, such languages are generic, 
specifying documents In such a way ‘that they can.be | . 
produced for a variety of different output devices, from type- 
writers to typesetters. This approach Is the very antithesis of 
simple WYSIWYG, whicli uses the screen as an exact repre- 
sentation of a single final paper result. 

In a generic markup language; writers specify tholrintent 
for. a particular part:of the document without specifying any of 
the details-of its appearance. For example, the generic name 


for.a fist with.bulieted paragraphs might be “highlighted-list.” 


Systems. SCT provides the mechanism 


Incremental update. Large documents 
are created by teams of writers and 


This name specifies only the nature of the effect wanted, not 


Generic specific i rome of advantages over sim- 
ple WYSIWYG editiig oF Highly procedural formatting lan- 
guages: 

© Writers don't have to tetnemtier details of the local con- 
ventions for the appearance-of various effects, only the kind 
of effect they, want and ity.fame. 

* Editing Is faster bécausé thé narhe. implies many 
parameters, like. changes in margins, spacing, style, and 
placement ofpailett, tat Gthérwise would have to be speci- 
fied manuatty. 

« Writers don’t have to waste time on formatting in the early 
stages of development. 

*.Subeequent maintainers can. $@6 what the original author 
nets not just what the dogument looked like, . : 

© Geseric-termatiing apec Heations are device- 
independent,.giving. mare flexibility and Higher quality for a 
range of output devices. 

* Corpérate formatting standards can be established and 

i rer necessary without affecting t books under 
nd- | a document, WYSIWYG editors 
ry! tiriy lariguages pro- 
jg Fhese appre ‘do fit dffer the same power 

asa sbenins description language. 

With the advantages of generic markup languages, you 
might wonder why simple WYSIWYG editors have such power 
in the marketplace. Undoubtedly there are many answers to 
this questiod:* Aside from WYSIWYG's reots in the typing poo! 


2 eng a gerinral tack of understanding. of document atstrac- 


tions, one of the answers {ies in the convenience and aes- 


tneting ateneganca editing itself. 
Bt.OF I oy 0 tang vi ines 


uty o srnbedchtyoosee se correctly, and sorting out 
ing; ab thal iararely any debugging 
big systortis make the document source 
: OlTORted tous ari ‘herice make: thejob of womens oe it 
; — in “— of the advantages. 


1. LE: KK, Fre -TEXbook, ag eaebiogs ley, Reading, Mass., 1984. 
2. Complies Comes ADocument Spectiication Lahipeebe and its” 
N ; le: Melion University, Pittsburgh, Penn. Dac. 1980. 
nbs, AH. "Renear, and S.J. DeRose, “Markup Systems and 
‘ia faimet chor Text a Acer Comm. ACM, Nov. 1987, 
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engineers whose work can be highly inter- 
dependent; sections from one book need 
to refer to those in another. Using Concor- 
dia, you can add your changes to the data- 
base daily (or more often), which makes 
those changes available immediately to 
anyone else working on the same project. 


Version and configuration control. SCT 
records the source and update files that 
constitute any particular version of a docu- 
ment. Asa result, document versions and 
software versions are coordinated auto- 
matically. A particular system version can 
be distributed and its files marked to pro- 
tect them against deletion. 


Evaluation 


The document development methodol- 
ogy in Concordia has been used in-house 
at Symbolics since late 1983. The 
documentation group has consisted of 
eight writers (on average), one editor, one 
supervisor, and one person responsible for 
production, each equipped with a Sym- 
bolics workstation and software. In this 
four-year period, the group has published 
three major editions of the Symbolics 
document set, ranging in size from 2500 
pages (1984) to over 7500 pages (1987). 
Each new edition was completely 
reprinted. Several minor releases inter- 
vened between the major releases, each 
with release notes and sometimes newly 
added documents. 

The writing group members are not the 
only users of Concordia. Many software 
developers also use Concordia for organ- 
izing design documents and for first-draft 
reference documentation. 

Our approach to document develop- 
ment has been particularly successful in 
the following areas: 


© Fast prototyping. New documents 
based on existing material can be put 
together in days. New organizations for 
existing documents can be tried out 
quickly and maintained in parallel with the 
original. 

© On-line delivery. A single document 
database is used for both on-line delivery 
and paper manuals; both media deliver 
exactly the same documents. With our dis- 
play hardware and Document Examiner 
interface, we have found on-line delivery 
an acceptable alternative to paper. 

© Quality enhancement. Since the in- 
house engineering community has access 
to the document database, documents are 
actually in use during development. As a 
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result, users can report errors and usabil- 
ity problems as documentation bugs via 
electronic mail. Minor revisions are 
immediately available. 

© Maintenance. Writers can update 
documents easily by replacing erroneous 
records or by adding new ones, and 
updated records are distributed electron- 
ically to customers as part of minor 
releases. The writing staff can respond 
quickly and easily to problem reports 
because changes do not result in change 
pages. They manage updates with the same 
configuration tools as used for software 
changes. 


We plan to continue using Concordia 
for developing documentation at Sym- 
bolics, extending it as our needs expand. 
We see anumber of areas needing further 
research and exploration: 


(1) Project support. Documentation is 
produced by groups of people coordinat- 
ing their efforts with other groups of peo- 
ple. We need to address further technical 
aspects of this coordination. 

(2) Understanding modular writing. We 
need more research to understand the dif- 
ficulties inherent in technical communica- 
tion, particularly in the rhetoric of 
modular writing. 


his approach is feasible for 
producing large-scale documen- 
tation. Using it, our writers have 
become highly productive in a demanding 
development environment. 
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